home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 151-175 / scopedisk161 / keymaped / keymaped.doc < prev    next >
Text File  |  1995-03-19  |  13KB  |  319 lines
  1.                Key Map Editor
  2.                  Tim Friest
  3.                  May, 1990
  4.  
  5.                 version 1.1i
  6.  
  7. ***************************************************************************
  8. * The KeyMapEditor is copyright © 1989,1990 to Tim Friest          *
  9. *                                      *
  10. * this program is FREE, you may copy it or distribute it as long as there *
  11. * is no charge for the program (small handling fees are allowed if this   *
  12. * program is distributed on a disk with other PD/FreeWare/ShareWare      *
  13. * programs or on a charge BBS), and the executable is unaltered and this  *
  14. * file accompanies it.                              *
  15. *                                      *
  16. * please send any and all comments and/or bug reports to:          *
  17. *                                      *
  18. * USMail:    Tim Friest        bitnet: AXTBF@ALASKA.BITNET      *
  19. *        3861 Steller Dr.                      *
  20. *        Anchorage, AK 99504    bix:    TFRIEST              *
  21. *                                      *
  22. * Voice:    (907) 333-8199                          *
  23. *                                      *
  24. * Compiled with Lattice C 5.05                          *
  25. *                                      *
  26. ***************************************************************************
  27.  
  28. Introduction:
  29.  
  30. KeyMapEd allows you to modify the KeyMaps destributed by Commodore-Amiga
  31. with AmigaDOS.  These KeyMaps may then be installed on your system with
  32. the SetMap command.
  33.  
  34. Basically, any key may have 'key macros'.  Each key may have a seperate
  35. value for pressing the key alone, with shift, with alt, with shift & alt,
  36. with control, with control & shift, with control & alt, and with shift, alt,
  37. & control (the latter is refered to as vanilla).  Thus, each key may have up
  38. to 8 seperate values when pressed.  Further, keys may be capsable (use the
  39. shift value when the caps lock key is on) and/or repeatable (key repeats
  40. when held down).  Finally, pressing the combination of a dead key with a
  41. key that is deadable (modified by a dead key) allows the addition of accents
  42. to the key value (for instance an 'alt-g' then 'a' will produce an 'à' or an
  43. 'a' with an accent grav above it).
  44.  
  45. Any program which is written correctly and uses the default keymap will
  46. fully support all these features and fully support any changes you make
  47. to your keymap.  Unfortunately there are many programs which are not written
  48. correctly and/or do not use the default keymap (hint! hint! developers!!!).
  49.  
  50. I believe that with this utility, it will be much easier to write a program
  51. which uses a special keymap, and still fully support the keymap capabilities,
  52. than to hardcode what each key does within the progam.
  53.  
  54. Note:    SetMap adds the keymap to a list in memory and if you do
  55.  
  56.         SetMap usa1
  57.         SetMap f
  58.         SetMap usa1
  59.  
  60.     SetMap will only read usa1 once!  Further, usa1 and f will both
  61.     remain in memory until you reboot.
  62.  
  63.     This impacts KeyMapEd since modifying a keymap that you've already
  64.     done a SetMap on, then trying to SetMap it again, will not update
  65.     the keymap in memory (it will just use the version it had already
  66.     loaded into memory).   You would have to save the keymap out under
  67.     a different name from KeyMapEd to get SetMap to use the new version.
  68.     The name is hardcoded in the file, so it is recommended you do not
  69.     rename the file.  The reason for this is that SetMap compares the
  70.     name within the file to the keymap that is requested, and if it is
  71.     the same, the version already in memory is used.  Supose you edited
  72.     the usa1 keymap, saved it as usa1 and then renamed it to foo.  Then
  73.     you changed your Startup-Sequence to do a SetMap foo instead of
  74.     SetMap usa1 (which is normal for A500/A2000s).  The system still
  75.     thinks that the keymap it has loaded is usa1 (not foo) since that was
  76.     the name coded in the file... For this reason, doing a SetMap usa1
  77.     will not load in usa1, but use the one in memory (which is really foo).
  78.     Also, SetMap foo will load another copy of foo into memory since
  79.     foo doesn't match usa1.
  80.  
  81. Description:
  82.  
  83. There are four basic types of keys definable within a keymap.
  84.  
  85.  
  86. NOP
  87.  
  88. A NOP key does nothing, and has no value.
  89.  
  90.  
  91. Normal (NoQual)
  92.  
  93. A normal key may contain up to 4 single character values (plus a special
  94. value for vanilla keys).  This format uses the least amount of space, so
  95. you should use this if possible (as apposed to the next two).
  96.  
  97. The four values can correspond to any combination of the key alone with
  98. up to two of the shift/alt/ctrl combinations.  If you want the key to be
  99. vanilla, the ctrl key modifies the value of certain alphabetic keys plus
  100. some others (@ for example), giving you 5 values for that key.  For example
  101. the 't' key contains the values 't', 'T', alt-t '\xfe', alt-T '\xde', and
  102. ctrl-t '\x14' (note the ctrl-t value isn't actually stored, it is calculated).
  103.  
  104.  
  105. String
  106.  
  107. A string key may contain all 8 possible values, and each value may be up
  108. to 32 (as of AmigaDOS v1.3) characters in length.  A good example of string
  109. keys are the function keys, the arrow keys, or the application keys.  These
  110. keys will send a string whenever the key is pressed.  This is basically what
  111. will give you that 'key macro' capability.  Any key which is not dead or
  112. deadable may be string and output up to 8 different 32 character values
  113. when pressed.  Therefore, if you want alt-f10 to issue a 'list dh0:" command
  114. you could simply code that into the keymap.
  115.  
  116.  
  117. Dead
  118.  
  119. Dead keys output up to a single character in one of three ways.  A key that
  120. is dead (when you press it it modifies the value of the next key pressed), a
  121. key that is deadable (modified by a dead key), and a key that is uneffected
  122. by a dead key.  If a key is dead, it contains the value of the accent that
  123. it will use (for instance alt-k will produce an umlat with deadable keys).
  124. If a key is deadable, seperate values will be stored for each possible accent
  125. available on that key (there are currently five: accent accute (´), accent
  126. grav (`), caret (^), circumflex (~), and umlat (¨) (I produced these by
  127. pressing alt-f space, alt-g space, alt-h space, alt-j space, alt-k space with
  128. the USA1 keymap)).  Finally, if the key can not be modified by a dead key,
  129. then simply place the value in the keymap (for instance an alt-a is not
  130. modified by a dead key).
  131.  
  132.  
  133. Using KeyMapEd:
  134.  
  135. KeyMapEd will prompt for a keymap if you do not specify one.  It auto-
  136. matically assumes the keymap is located in devs:keymaps so you must specify
  137. the full pathname if it is not located there (SetMap requires the keymap
  138. be in devs:keymaps so you might as well put them there anyway).
  139.  
  140. The KeyMapEd window is very similar to KeyToy and should display the current
  141. value for each key with the current combination of shift/alt/ctrl/capslock.
  142. Simply press the shift/alt/ctrl/capslock gadgets to change the display.  The
  143. keyboard displayed is that of an Amiga 2000.  The keymap for an Amiga 500 or
  144. 1000 is exactly the same!  The A2000 keyboard has a few additional keys
  145. that the A1000 did not, and some of the keys have migrated, but other then
  146. that, the keymap for ALL keys on the A1000 keyboard is exactly the same as
  147. that for an A2000, there are just fewer values on the A2000 keyboard listed
  148. as unused (i.e. there are still spaces left so an A3000 might very well have
  149. even more keys then the A2000 and still be fully compatible with the A1000
  150. (at least keymap wise)).
  151.  
  152. Clicking on a key gadget other then the shift, alt, ctrl, or capslock will
  153. display the key editor window for that key.  Pressing the key on the keyboard
  154. will also work.
  155.  
  156. The top row of gadgets define what type of key this is (NOP, Normal, String,
  157. or Dead).  The second row shows which of the shift/alt/ctrl keys effect this
  158. key.  The third row displays whether the key is capsable and/or repeatable.
  159. Finally the rest of the window shows the values for each of the shift/alt/ctrl
  160. combinations available for this key.  The rest of the window will be different
  161. depending on whether the key is NOP, Normal, String, or Dead.
  162.  
  163. Values for a key will be displayed in standard C string format.  This means
  164. that if the value is normally printable, the value should appear, otherwise
  165. the hex value for the key will be displayed in the format '\x##'.  A few
  166. notable exceptions to this rule are certain of the common control codes have
  167. special values '\r' for return, '\n' for newline, '\f' for formfeed, etc.
  168. Finally, since the '\' is used as an introducer for the control sequences,
  169. you must use '\\' to specify a single backslash.
  170.  
  171. Since up to 4 characters may be used to specify a single character value,
  172. the string gadgets for a single value may hold up to 4 characters.  Please
  173. note that Normal keys and dead keys may contain 1 and only 1 value, and if
  174. you place more characters in the string gadget then what will equate to
  175. a single character, the string will be truncated to 1 character.  Likewise,
  176. String keys may only contain 32 characters, I have made the string gadget
  177. size 127 to hold many control sequences.  Again, the resultant string will
  178. be truncated to 32 characters.
  179.  
  180. Switching back and forth betwean the types of keys (NOP, Normal, String, and
  181. Dead) will produce strange results as strings are truncated to fit within
  182. certain limits or altered as dead or deadable keys.
  183.  
  184. Selecting either the Use or Cancel gadgets will end the key edit mode and
  185. either update the keymap or not depending.
  186.  
  187.  
  188. Saving the KeyMap:
  189.  
  190. Once you have gotten the keymap as you like, you will want to save it.
  191. Selecting the Save option from the Project Menu will give you a file requester
  192. which you may use to save the keymap either to the same filename as read or
  193. a new filename.  Again the default directory is devs:keymaps, and you must
  194. specify otherwise if you desire it to be elsewhere.
  195.  
  196. Note: The Key Map Editor uses the filename as the node name of the keymap,
  197.       thus if you save a keymap as USA1 the system will not differenciate
  198.       betwean the real (system) USA1 and your modified version, but if you
  199.       save it as NEWUSA1, the system will always see it as NEWUSA1 even if
  200.       you rename the file to USA1.  This is important to remember because
  201.       of the way SetMap works (see note at top).
  202.  
  203.  
  204. ---------------------------------------------------------------------------
  205.  
  206. Changes to v0.99 since v0.91:
  207.  
  208.     Fixed bug with interpretation of Vanilla keys for normal type
  209.  
  210.     Added options in options menus
  211.  
  212. ---------------------------------------------------------------------------
  213.  
  214. Changes to v1.0 since v0.99:
  215.  
  216.     Center text within gadgets on keyboard display
  217.  
  218.     Fixed return key (used Masked Boolean gadget so all of key
  219.     highlights when selected)
  220.  
  221.     Modified CTRL and CapsLock keys so rapidly and repeatly clicking
  222.     them would not continually refresh the screen (this already worked
  223.     on Shift and Akt keys)
  224.  
  225.     Fixed problem with key labels for NOP keys which causes GURUs
  226.  
  227.     Fixed a problem with deadable keys which were not Vanilla
  228.  
  229.     Fixed title/version number
  230.  
  231. ---------------------------------------------------------------------------
  232.  
  233. Changes to v1.01 since v1.0:
  234.  
  235.     Fixed a major bug when converting from one type of key to another
  236.     (for instance editing a normal key and changing it to a string
  237.     key caused a GURU)
  238.  
  239.     Fixed a problem with the key label centering code (didn't update
  240.     properly).
  241.  
  242. ---------------------------------------------------------------------------
  243.  
  244. Changes to v1.02 since v1.01:
  245.  
  246.     Fixed the Return key to not overright the ] when edited
  247.  
  248. ---------------------------------------------------------------------------
  249.  
  250. Changes to v1.03 since v1.02:
  251.  
  252.     Increased size of filename allowed by file requester to support
  253.     longer pathnames (i.e. keymaps outside of devs:keymaps)
  254.  
  255.     Fixed the Load and New options so that the modified requester
  256.     appears if the current keymap has been changed
  257.  
  258.     Fixed the file requester files list to stay where it was left
  259.  
  260.     Added a Reload gadget for the file requester so that the list
  261.     could be updated if things changed externally to the program
  262.  
  263.     Fixed guru which appeared when saving more then once
  264.  
  265. ---------------------------------------------------------------------------
  266.  
  267. Changes to v1.04 since v1.03:
  268.  
  269.     To fix guruing problem with 1.03, I simply recompiled it (no other
  270.     changes except version number...)
  271.  
  272.     Fixed Shift-Alt dead key to allow modified values
  273.  
  274.     Fixed copy/move to clear key before operation (free mem for
  275.     string/dead)
  276.  
  277.     Fixed copy/swap/move capsable and repeatble flag setting
  278.  
  279.     Fixed deallocation problem for keycodes 0x3F and 0x77
  280.  
  281. ---------------------------------------------------------------------------
  282.  
  283. Known Bugs/Features: v1.04 March 15, 1989
  284.  
  285.     String gadgets don't erase the last character when scrolled to the
  286.     right.  Seems to be a bug with intuition???
  287.  
  288.     Return key gadget erases part of ] key on refresh
  289.  
  290.     Clicking a gadget for the key editor requestor before it has finished
  291.     rendering will cause the computer to lockup
  292.  
  293. ----------------------------------------------------------------------------
  294.  
  295. Changes to v1.1 since v1.04
  296.  
  297.     Added key entry support to define a key (just press the key instead
  298.     of clicking on the gadget with the mouse).  This will allow support
  299.     for any key which is definable (for non-standard keyboards or future
  300.     keyboards with extra keys).
  301.  
  302.     Fixed return gadget using a masked boolean gadget.
  303.  
  304.     Fixed lockup problem.
  305.  
  306. ----------------------------------------------------------------------------
  307.  
  308. Changes to v1.1i since v1.1
  309.  
  310.     Added menu option to switch between European and American (English)
  311.     keyboards.  Added gadgets and support for extra keys.
  312.  
  313. ----------------------------------------------------------------------------
  314.  
  315. Known bugs in v1.1i
  316.  
  317.     Does not support Double-Dead keys.  I hope to add this sooner than
  318.     it has taken me to add the extra keys for European keyboards.
  319.